ASP.NET Core Web API 入門心得 - Middleware 順序
TLDR
- Middleware 的執行順序對於 ASP.NET Core 應用程式的正確性至關重要。
- 錯誤處理（如
UseDeveloperExceptionPage）應優先於所有其他 Middleware。 UseRouting必須位於UseCors、UseAuthentication與UseAuthorization之前。UseCors必須位於UseAuthentication與UseResponseCaching之前，以避免已知的 Bug。UseStaticFiles若涉及跨域請求、文化特性或壓縮，其位置需根據對應的 Middleware 進行調整。- 端點路由（如
MapControllers）必須放置在管線的最末端。
Middleware 功能說明
在 ASP.NET Core 管線中，各項 Middleware 扮演不同角色：
- 例外處理：
UseDeveloperExceptionPage用於開發環境回報錯誤；UseExceptionHandler則用於攔截後續 Middleware 擲出的例外。 - 安全性：
UseHsts新增Strict-Transport-Security標頭；UseHttpsRedirection將 HTTP 請求轉導至 HTTPS。 - 靜態資源：
UseStaticFiles負責處理靜態檔案請求。 - 身分驗證與授權：
UseAuthentication確認使用者身分，UseAuthorization檢查存取權限。 - 路由與端點：
UseRouting負責解析路由，UseEndpoints則執行最終的端點邏輯。
Middleware 完整順序建議
Middleware 的順序直接影響請求處理的邏輯，以下為建議的配置順序：
csharp
var app = builder.Build();
if (app.Environment.IsDevelopment()) {
app.UseMigrationsEndPoint();
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
} else {
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseRouting();
app.UseRateLimiter();
app.UseRequestLocalization();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
app.UseSession();
app.UseResponseCompression();
app.UseResponseCaching();
app.MapRazorPages();
app.MapDefaultControllerRoute();
app.Run();常見順序陷阱與注意事項
在配置 Middleware 時，需注意以下特定情境的順序限制：
UseStaticFiles：
- 什麼情況下會遇到問題：當應用程式涉及跨域請求、特定文化特性或需要壓縮快取時。
- 建議：若使用 JavaScript 擷取跨域靜態檔案，須放在
UseCors後面；若涉及文化特性，須放在UseRequestLocalization後面；若需快取壓縮檔案，須放在UseResponseCompression和UseResponseCaching後面。
UseCors：
- 什麼情況下會遇到問題：當 CORS 設定與快取或驗證機制衝突時。
- 建議：必須放在
UseRouting後面、UseAuthentication前面。此外，若放在UseResponseCaching後面，可能會觸發 https://github.com/dotnet/aspnetcore/issues/23218 的問題。
UseRouting 與 RateLimiter：
- 什麼情況下會遇到問題：當 RateLimiter 需要依賴路由資訊時。
- 建議：除非 RateLimiter 僅使用全域 Filter，否則
UseRouting必須放在UseRateLimiter前面。
UseRequestLocalization：
- 什麼情況下會遇到問題：當後續 Middleware 需要根據文化特性處理請求時。
- 建議：必須出現在任何檢查要求文化特性的 Middleware 之前。
異動歷程
- 初版文件建立。